Skip to content

Comments

Improvements to Advanced Tutorial doc #3266

Merged
Blargian merged 14 commits intoClickHouse:mainfrom
noramullen1:tutorial-updates
Apr 9, 2025
Merged

Improvements to Advanced Tutorial doc #3266
Blargian merged 14 commits intoClickHouse:mainfrom
noramullen1:tutorial-updates

Conversation

@noramullen1
Copy link
Contributor

@noramullen1 noramullen1 commented Feb 14, 2025

Fixes #3268

Summary

  • Various style and grammar updates, including the following:

    • Avoid ellipses (reference)
    • Hyphen vs. em dash (reference)
    • Key-value, not “key -> value” (reference)
    • Headings should be sentence case (reference)
    • Use the serial comma (reference)
    • Use parentheticals only when needed (reference)
    • No exclamation points (reference)
    • Use negation contractions (reference)
    • Don't capitalize feature names like dictionary (reference)
    • Consistency fixes: New York City/NYC, primary key/primary index, compute/calculate, switching between first and second person for the audience (it should always be second)
  • Remove "marketing lingo"

    • Superlative language like "blazing fast", "amazing collection", or "the s3 cleverly knows" doesn't fit with the purpose or tone of product documentation.
    • Product docs should be clear, concise, and focused on showing them how to do the task at hand.
  • Organization and user experience

    • Don't number h2s.
    • Collapsed expected output code blocks for queries section to make it more scrollable.
    • Including dictionaries link in-line instead of telling user to scroll to the bottom.
    • Link to existing description for LIFETIME instead of trying to reinvent the wheel here.
    • Use note formatting sparingly to avoid fagtigue.
    • Final section was randomly h4 nested under the Perform a join section.
  • Example says "right join" but code shows inner join

@CLAassistant
Copy link

CLAassistant commented Feb 14, 2025

CLA assistant check
All committers have signed the CLA.

```
:::note
Generally, we avoid using `SELECT *` often in ClickHouse. You should only retrieve the columns you actually need. However, in this example, we wanted it to be slow because why?
:::
Copy link
Contributor Author

@noramullen1 noramullen1 Feb 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear to me why you'd want this query to be slow.

1. Connect to the SQL console
The New York City taxi dataset contains details about millions of taxi rides, with columns including tip amount, tolls, payment type, and more. Create a table to store this data.

<SQLConsoleDetail />
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two giant screenshots seem extremely unnecessary and disruptive to the reader's experience.

@Blargian
Copy link
Member

@noramullen1 This is our 13th most viewed page, so thank you for the very valuable contribution! :)

Spell check is failing on these words:

====== /home/runner/work/clickhouse-docs/clickhouse-docs/docs/en/tutorial.md ======
Allerton
Boro
LocationID
Pelham
york

As they're part of a query response we just need to add them as exceptions here: https://github.com/ClickHouse/clickhouse-docs/blob/main/scripts/aspell-dict-file.txt

Add spelling exceptions
@noramullen1 noramullen1 requested a review from a team as a code owner February 27, 2025 23:59
@noramullen1
Copy link
Contributor Author

@noramullen1 This is our 13th most viewed page, so thank you for the very valuable contribution! :)

Spell check is failing on these words:

====== /home/runner/work/clickhouse-docs/clickhouse-docs/docs/en/tutorial.md ======
Allerton
Boro
LocationID
Pelham
york

As they're part of a query response we just need to add them as exceptions here: https://github.com/ClickHouse/clickhouse-docs/blob/main/scripts/aspell-dict-file.txt

Ah, thanks @Blargian! I added them to the file, looks like it's passing the spell check now. (sorry for the delay, realized my account was linked to an outdated email address!)

@Blargian Blargian mentioned this pull request Apr 9, 2025
3 tasks
@Blargian Blargian merged commit 4f34779 into ClickHouse:main Apr 9, 2025
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve Advanced Tutorial doc

3 participants